TeamA

id: task-100.7 title: Bundle web assets into executable status: Done assignee: [] created_date: '2025-06-22' updated_date: '2025-07-06' labels: [] dependencies:

  • task-100.1
  • task-100.2
  • task-100.6 parent_task_id: task-100

Description

Configure build process to embed React app in CLI executable. This is crucial for distributing Backlog as a single binary that contains both the CLI and web UI.

Build Process Overview

Build Process Requirements

Two-Stage Build:

  1. Build React app to optimized static files
  2. Embed static files into CLI executable using Bun's native directory embedding

Asset Embedding Strategy (Bun v1.2.17+):

  • Use shell glob patterns with bun build --compile to embed directories
  • Leverage Bun's native Bun.embeddedFiles API for accessing embedded assets
  • Eliminate need for custom build scripts and manual asset generation

Native Directory Embedding:

  • Use bun build --compile ./src/cli.ts ./src/web/dist/**/*.* --outfile=backlog
  • Access embedded files via Bun.embeddedFiles array of Blob objects
  • Automatically handles asset discovery and embedding

Vite Configuration Requirements:

  • Configure production build optimization
  • Set up code splitting for vendor libraries
  • Enable proper asset hashing for cache busting
  • Optimize bundle size with tree shaking and minification

Static Asset Serving:

  • Access embedded files using Bun.embeddedFiles API
  • Map file paths to embedded Blob objects
  • Handle proper MIME types for different file extensions
  • Implement appropriate caching headers
  • Support SPA routing (fallback to index.html)

Package Scripts Integration:

  • Simplify build process using native embedding
  • Build script: bun build --compile ./src/cli.ts ./src/web/dist/**/*.* --outfile=backlog
  • Eliminate need for separate asset embedding step
  • Support both development and production builds

Embedded File Access:

  • Use Bun.embeddedFiles to get array of all embedded files
  • Each file is a Blob object with metadata
  • Map original file paths to embedded file references
  • Handle file serving directly from embedded Blobs

Reference Documentation

Essential Reading for Implementation:

Key Implementation Patterns:

  • Use shell glob patterns to embed directories: ./src/web/dist/**/*.*
  • Access embedded files via Bun.embeddedFiles array
  • Serve files directly from Blob objects without conversion

Optimization Techniques

  • Code Splitting: Separate vendor chunks for better caching
  • Tree Shaking: Remove unused code
  • Minification: Terser for JS, cssnano for CSS
  • Compression: Brotli compression for text assets
  • Asset Hashing: For cache busting
  • Lazy Loading: Dynamic imports for route-based splitting

Acceptance Criteria

  • [x] Vite builds React app to optimized dist/ directory
  • [x] Shell glob pattern embeds entire dist/ directory using bun build --compile
  • [x] Embedded assets accessible via Bun.embeddedFiles API
  • [x] Server can serve embedded files directly from Blob objects
  • [x] Build process simplified without custom embedding scripts
  • [x] Production build is optimized with proper asset hashing
  • [x] SPA routing works correctly with embedded index.html fallback
  • [x] All file types (HTML, CSS, JS, images) served with correct MIME types
On this page

    1. Description
    2. Build Process Overview
      1. Build Process Requirements
    3. Reference Documentation
      1. Optimization Techniques
    4. Acceptance Criteria

Brodocs MVP